Getting Started

adaptor:ex hilft dir Interaktive Performances, Theater-Games, Installationen, Chatbot-Adventure oder Escape Rooms zu erstellen. Die grafische Programmieroberfläche ist darauf optimiert Dramaturgie und Game Mechanik Zusammenzubringen und übersichtlich anzuordnen.

Du kannst schnelle Anpassungen während der Proben vornehmen und den Live Ablauf während der Tests und Aufführungen überwachen und kontrollieren.

Der adaptor:ex Editor wird über den Browser aufgerufen, sodass ihr mit mehreren Leuten das selbe Game editieren und kontrollieren könnt.

Hier findest du mehr darüber hinaus, wie du mit adaptor:ex deine Storyline, Game Mechanik, Software und Hardware miteinander verdrahtest und unter Kontrolle bringst.

Hole und installiere dir adaptor:ex auf deinem lokalen Rechner oder auf einem Server. Es gibt verschiedene Wege für die Installation.

Beginne mit einem Tutorial, wenn du eine der verschiedenen Möglichkeiten kennenlernen willst auf die du adaptor:ex zu nutzen kannst.

Im Glossar sind die Grundbausteine, Actions und Plugins genauer beschrieben.

Installation

Um adaptor:ex zu installieren musst du derzeit die Kommandozeile deines Betriebssystems nutzen. Unter macOS suche das Programm "Terminal". Unter Linux findest du das Terminal unter der Tastenkombination [ctrl] + [alt] + [T]. Unter windows suche die Anwendung "Eingabeaufforderung" bzw. "Commandline".

Es stehen drei Installationsmöglichkeiten zur Auswahl: NPM, SOURCE und DOCKER.

Wenn du die Anschlüsse an deinem Rechner nutzen willst, z.B. den Seriellen Anschluss per USB oder eine Soundkarte, installiere adaptor:ex mit NPM oder via SOURCE.

Im besonderen für eine Server Installation empfehlen wir die Installation in einem Docker Container.

adaptor:ex ist gerade erst an den Start gegangen. Wir werden in den kommenden Monaten häufig Fehler beheben, Dinge (hoffentlich) verbessern und neue Features hinzufügen. Führe hin und wieder ein Update via NPM oder Docker durch, um auf dem neuesten Stand zu bleiben.

Melde dich bei uns, wenn du Schwierigkeiten hast, adaptor:ex zu installieren. Schreib uns an tech@machinaex.de oder schau auf unserem Discord vorbei.

Installieren mit NPM

Bevor Du mit der Installation von adaptor:ex fortfahren kannst, brauchst Du die aktuelle Version von NodeJS. Die nötigen Installatiosdateien für dein Betriebssystem findest Du hier.

Sobald Du NodeJS installiert hast, öffne deine Konsole bzw. das Terminal und führe in der Kommandozeile die Installation mit npm aus

Auf macOS und Linux

sudo npm install -g adaptorex --unsafe-perm

Auf Windows

npm install -g adaptorex --unsafe-perm

Wenn die Installation erfolgreich war, starte adaptor:ex mit dem Kommando

adaptorex

Möglichkeiten adaptor:ex zu Konfigurieren findest du in der adaptor:ex server readme

Um den adaptor:ex server wieder zu beenden benutze die Tastenkombination [Strg] + [C] (windows/linux) bzw. [Cmd] + [C] (MacOS), oder gib quit in die Konsole ein.

Updates mit NPM

Lade dir die neueste Version von adaptor:ex herunter indem du die obige Installation wiederholst.

Mit npm outdated -g kannst du überprüfen ob eine neue Version zur Verfügung steht.

Installieren von Source mit NPM

Bevor Du mit der Installation von adaptor:ex fortfahren kannst, brauchst Du die aktuelle Version von NodeJS. Die nötigen Installatiosdateien für dein Betriebssystem findest Du hier.

Hole dir adaptor:ex Server und Client:

Server

Klone oder lade dir das aktuelle GitLab-Repository des adaptor:ex Servers hier herunter: https://gitlab.com/machina_ex/adaptor_ex/adaptor_ex_server

Client

Klone oder lade dir das aktuelle GitLab-Repository des adaptor:ex Clients hier herunter: https://gitlab.com/machina_ex/adaptor_ex/adaptor_ex_client

Jetzt kannst du den Server und den Client mit NPM lokal installieren.

Wechsel im Terminal (der Konsole) in das Verzeichnis in das du den Server oder Client geladen oder geklont hast.

cd adaptor_ex_server/

bzw.

cd adaptor_ex_client/

Wenn du in dem richtigen Verzeichnis bist führe den folgenden Befehl aus:

npm install

Wenn die Installation erfolgreich war, starte den adaptor:ex Server im entsprechenden Verzeichnis mit dem Kommando

node index.js

Starte anschließend, in einer separaten Commando Zeile, den adaptor:ex Client im entsprechenden Verzeichnis mit dem Kommando

npm run serve

Updates mit git

Lade dir die neueste Version von adaptor:ex server und client herunter indem du im jeweiligen Verzeichnis das Git Repository mit folgendem Befehl updates

git pull

Starte den adaptor server und client anschließend neu.

Telegram Erweiterung installieren

Um das Telegram Plugin in adaptor:ex nutzen zu können musst du zusätzlich python und einige python Bibliotheken installieren. Folge den Anweisungen der adaptor:ex Telegram Plugin Readme.

Installieren mit Docker

Lade Docker für dein Betriebsystem herunter und folge den Installationsanweisungen auf https://docs.docker.com/get-docker/

Erstelle einen neuen Ordner in dem du adaptor:ex installieren willst.

Öffne deine Kommandozeile, wechsle mit dem cd command in das adaptor:ex verzeichnis und lade die adaptor:ex docker-compose Datei herunter:

curl -o docker-compose.yml https://gitlab.com/machina_ex/adaptor_ex/adaptor_ex_server/-/raw/main/docker-compose.yml

Führe die Docker Compose Datei aus:

docker-compose up -d

adaptor:ex Server, Client, Datenbank und Plugin Erweiterungen werden heruntergeladen und installiert.

In der adaptor:ex server readme kannst du mehr über die Konfiguration von adaptor:ex erfahren.

Updates mit Docker

Um die adaptor:ex Docker installation zu aktualisieren wechsle in das adaptor:ex Verzeichnis. Dort führe folgende Kommandos aus:

docker-compose pull

und anschließend

docker-compose up -d

Erste Schritte

Gebe die URL, also die webadresse, deines adaptor:ex setups im Web Browser ein.

Wir empfehlen die aktuellste Version von Google Chrome oder Firefox zu verwenden.

Wenn du adaptor:ex mit den Standardeinstellungen auf deinem Rechner oder Laptop installiert hast, kannst du auch auf einen dieser links klicken: http://localhost:8081 (Installation per NPM) oder http://localhost:8080 (Source Installation).

Hast du adaptor:ex auf einem Server oder einem anderen Rechner installiert musst du die URL durch die IP oder den Domainnamen deines Servers ersetzen.

Ein Game erstellen

Beginne damit, ein neues Game Projekt anzulegen. Klicke auf New Game und gib deinem ersten Game einen Namen.

Level hinzufügen

Wenn du das neu erstellte Game Projekt anklickst, landest du in der Übersicht, die alle existierenden level anzeigt. Jedes Game kann aus mehreren Leveln bestehen, die auf verschiedenste Art miteinander verknüpft sind.

Erstelle dein erstes Level mit Add new.

Games und Level bekommen eine eigene Web Adresse, über die sie im Web Browser erreichbar sind. Darum darf der Name keine Leerzeichen oder Sonderzeichen enthalten.

Gib dem Level einen Namen und klicke auf Add new Level.

Level bearbeiten

Öffne das level anschließend, indem du auf den Namen klickst. Jetzt befindest du dich im level Editor.

Start (START) und Endpunkt (QUIT) deines Levels existieren bereits.

Suche aus der linken Seitenleiste, den actions, die control action Log Message heraus und ziehe sie per Drag and Drop auf die Mitte der Seite.

Es entsteht ein neues State Element, dass eine Log Message action enthält (log_1).

Klicke auf die neue action, um sie zu bearbeiten. Schreibe einen kurzen Text in das message Eingabefeld und wähle im level Dropdown info aus.

Um dein Level verständlicher zu gestalten, ist es gut allen States nachvollziehbare Namen zu geben.

Auch State Namen dürfen keine Leerzeichen beinhalten, da sie in Variablen zum Einsatz kommen können

Klicke in die Titelzeile deines Log Message State und benenne ihn um.

Bearbeite auch die Next action next_1 im START State indem du sie anklickst. Wähle dann den neuen State, hier HelloWorld, aus dem next state Dropdown aus um ihn mit dem START State zu verbinden.

Level starten

Wechsel vom Bearbeitungs in den Live Modus, indem du auf den Play button in der oberen rechten Ecke klickst

Die linke Seitenleiste mit den actions schließt sich und ein Menü öffnet sich an der rechten Seitenleiste.

Klicke in der rechten Seitenleiste auf Create Session und dann auf Start Session um eine Session von deinem Level zu erstellen.

Die neu gestartete Session ist in der rechten Seitenleiste ausgewählt.

Der HelloWorld State ist bereits hervorgehoben.

Wenn wir eine neue Session von einem Level erstellen, wird automatisch der START State ausgelöst. Die next_1 action hat direkt danach zu unserem State HelloWorld mit der Log Message weitergeführt.

Öffne die Log Konsole, indem du auf den cursor icon klickst.

Die neueste Log Nachricht sollte 'Hello World!' sein.

Indem du auf den HelloWorld State klickst, kannst du ihn manuell erneut auslösen. Beobachte die Log Konsole ob die Nachricht erscheint.

Level automatisieren

Wechsel zurück in den Bearbeitungsmodus, indem du erneut auf den Live Play Button klickst.

Suche die Timeout action in der rechten Seitenleiste heraus und ziehe sie auf den START State.

Wenn du die action darüber ziehst wird der State hervorgehoben und zeigt an, dass die action diesem State hinzugefügt wird, anstatt einen neuen State zu erstellen.

Wenn wir einem State eine action hinzufügen, die auf etwas wartet, wie ein timer der abläuft, ersetzt sie automatisch eine etwaige Next action.

Bearbeite den timeout. Gib eine kleine Zahl Sekunden im timeout feld an und wähle den HelloWorld State als next state aus.

Füge auch dem HelloWorld State eine Timeout action hinzu. Bearbeite den Timeout und wähle diesmal Quit als next state aus.

Wenn du nun in den Live Modus wechselst und eine neue Session startest werden die States in festen Zeitabständen nacheinander ausgelöst.

Sobald der QUIT State erreicht ist, wird die session beendet und verschwindet aus der rechten Seitenleiste.

Deine erste Session wird sich nicht automatisch beenden. Um sie zu beenden kannst du sie in der rechten Seitenleiste schließen (x) oder den QUIT State auslösen wenn du die Session ausgewählt hast.

Jede Session basiert immer auf der aktuellsten Version des Levels. Wenn jedoch der State, in dem sich eine Session befindet, verändert, muss er erneut ausgelöst werden.

Nächste Schritte

In der Referenz findest du mehr über die verschiedenen Grundbausteine von adaptor:ex heraus.

Tutorials leiten dich Schritt für Schritt durch Projekte die du mit adaptor:ex umsetzen kannst.

Lerne zum Beispiel, wie du das Telegram plugin einsetzt, um ein messenger Adventure zu entwickeln: Storytelling mit Telegram und adaptor eX

Oder beginne damit, einen Arduino mit adaptor:ex anzusteuern: Arduino Serial

Autoren und Unterstützer

Dies ist ein machina commons Projekt von machina eX.

gefördert durch

Senatsverwaltung für Kultur und Europa Berlin